.\" Copyright (c) 2009 LAAS/CNRS
.\" Copyright (c) 2001 by David Brownlee (abs@NetBSD.org)
.\" Absolutely no warranty.
.\"
.\" From $NetBSD: pkg_chk.8,v 1.26 2008/05/02 19:10:26 apb Exp $
.\"
.Dd Mar 22, 2009
.Os Robotpkg
.Dt ROBOTPKG_CHK \&8 "Robotpkg Administrative Tools"
.Sh NAME
.Nm robotpkg_chk
.Nd check, and optionally update, installed packages
.Sh SYNOPSIS
.Nm
.Op Fl abghiIklnpqrsuv
.Op Fl C Ar conf
.Op Fl L Ar file
.Op Fl P Ar path
.Sh DESCRIPTION
.Nm
verifies that the versions of installed packages match those in
robotpkg, optionally adding missing or updating mismatched packages.
.Pp
It can verify all installed packages, or check against a set of packages
specified in a configuration file.
.Pp
When updating packages that depend on each other
.Nm
will tsort the dependencies to reduce unnecessary rebuilding.
.Pp
The most common usage is
.Nm
.Fl u
.Fl q
to check all installed packages
or
.Nm
.Fl u
to update all out of date packages.
.Nm
.Fl i
will also update all out of date packages, by replacing them one at a
time.
.Pp
.Ss Options
.Bl -tag -width xxxxxxxx
.It Fl a
Automatically add any missing packages.
If a binary package exists in
.Pa ${PACKAGES}
it will be used in preference to building from source, unless the
.Fl b
or
.Fl s
options are given.
.It Fl b
Use binary packages.
If
.Fl s
is not set this allows
.Nm
to run without robotpkg sources.
.It Fl C Ar conf
Use the
.Pa robotpkg_chk.conf
file
.Sq Ar conf .
.It Fl g
Generate an initial
.Pa robotpkg_chk.conf
file based upon the packages installed on the host machine.
.It Fl h
Brief help.
.It Fl i
Automatically update any outdated packages and packages that have unsafe
dependencies.
Replacement is done by doing ``make replace'' in the topological order of
installed packages.
Whenever ``make replace'' is run on a package, all installed packages that
depend on it are marked with the ``unsafe_depends_strict=YES'' flag.
If the version of the replaced package has changed, this indicates that it may
no longer be ABI-compatible so ``unsafe_depends=YES'' is also set for all
packages that depend on it.
.Fl i
will restore packages with the unsafe_depends flag to a safe state.
.It Fl I
Same as
.Fl i
but replace outdated packages and packages with the unsafe_depends_strict
flag.
This has the same effect as
.Fl u
but by replacing one package at a time instead of deinstalling all packages
first.
.It Fl k
Continue with further packages if errors are encountered.
.It Fl L Ar file
Redirect the output for all commands run into the logfile
.Pa file .
On any error the tail end of the logfile will be displayed.
.It Fl l
List the filename for all binary packages (including best dependencies) based
on
.Pa robotpkg_chk.conf .
Will abort if a binary package is missing.
This can be used to determine what
packages would need to be copied to a remote machine to ensure it
was completely up to date.
The list is sorted so that dependencies
always come before packages which depend upon them.
.It Fl n
Display actions that would be taken, but do not change anything.
.It Fl P Ar path
Set the path to the binary packages.
Defaults to
.Ev PACKAGES
if
.Ev ROBOTPKG_DIR
is available, or
.Dq Pa \&.
otherwise.
.It Fl p
Print list of package directories that will be checked, then exit.
.It Fl q
Do not display actions or take any action; only list information
about package version differences.
Useful for options that list information about package differences, such as
.Fl a
or
.Fl u .
.It Fl r
Recursively delete any mismatched packages found.
Use with care, this does not record which packages were installed
for later update.
.It Fl s
Building missing packages from source.
If UPDATE_TARGET=package is set in
.Pa robotpkg.conf ,
then
.Nm
will automatically generate binary packages for later reuse.
.It Fl u
Automatically update any installed packages for which a more recent version
exists.
If a binary package exists in
.Ev PACKAGES
it will be used in preference to building from source, unless the
.Fl b
or
.Fl s
options are given.
.Pp
Note: If the update fails (particularly when building from source), the system
will be left with missing packages.
Once the error has been fixed, a second run will resume the update.
.It Fl v
Verbose - list all packages checked.
.El
.Sh FILE FORMAT
Anything after a
.Sq #
on a line is considered a comment.
.Pp
Each line in
.Pa robotpkg_chk.conf
defines a package directory (such as pkgtools/robotpkg_chk) which is used to
determine which packages are to be installed.
.Sh ENVIRONMENT
.Nm
uses the following environment variables.
.Bl -tag -width xxxx
.It Ev MAKECONF
Path to
.Pa robotpkg.conf .
Defaults to
.Pa @PREFIX@/etc/robotpgk.conf ,
or
.Pa /opt/openrobots/etc/robotpkg.conf .
.It Ev ROBOTPKG_DIR
Base of robotpkg tree.
Defaults to
.Pa @ROBOTPKG_DIR@ .
.It Ev PACKAGES
Location of binary packages.
If not set in environment then read from
.Pa ${MAKECONF} .
Defaults to
.Pa ${ROBOTPKG_DIR}/packages .
.Pp
Unless in a completely homogeneous environment (every machine running
exactly the same OS version and architecture) setting
.Ev ${PACKAGES}
in
.Pa robotpkg.conf
to a value such as
.Bd -literal
${ROBOTPKG_DIR}/packages/${LOWER_OPSYS}-${OS_VERSION}-${MACHINE_ARCH}
.Ed
.Pp
is strongly recommended.
If
.Em cpuflags
(devel/cpuflags) is being used to optimally target individual CPU types,
then
.Ev ${CPU_DIR}
should be appended to
.Ev ${PACKAGES} .
.El
.Sh EXAMPLES
Sample
.Pa robotpkg_chk.conf
file:
.Bd -literal

# Install before others
pkgtools/robotpkg_chk

# Others
shells/eltcsh
architecture/genom

.Ed
.Sh AUTHORS
.An Adapted by Anthony Mallet from pkg_chk(8) in pkgsrc. pkg_chk(8) from David
Brownlee
.Aq abs@NetBSD.org ,
plus much from Stoned Elipot.
.Sh BUGS
When used against binary packages,
.Nm
does not handle the directory containing multiple versions of the same package.
